Pipelines semánticas

Las pipelines semánticas describen cómo circulan por Guida los datos sujetos a un contrato. Conectan una fuente o un extractor con validadores, mapeadores y destinos, y permiten revisar el trabajo propuesto antes de ejecutarlo.

Una pipeline no es una carpeta de flujo de trabajo, un grupo de procesos de trabajo ni un planificador desatendido. Los flujos activan el ámbito operativo, los procesos consumen colas y el registro de trazabilidad conserva la información duradera de ejecuciones y elementos. La pipeline une estos ámbitos con una procedencia explícita.

Modelo por etapas

Etapa	Responsabilidad
Source	Declara el tipo o esquema de entrada
Extractor	Ejecuta un contrato de extractor identificado
Validator	Aplica un esquema y reglas acotadas por elemento
Mapper	Transforma un contrato declarado en otro
Destination	Identifica una cola u otro destino compatible

Los validadores, mapeadores y destinos son catálogos reutilizables. Así, las reglas y las formas de los datos no quedan ocultas en scripts aislados.

{
  "id": "careers.example.discovery-to-fetch",
  "workflowName": "careers-crawl",
  "status": "draft",
  "stages": [
    { "id": "discover", "kind": "extractor", "extractorId": "careers.example.jobs" },
    { "id": "validate", "kind": "validator", "schema": "schemas/career-job-output.schema.json" },
    { "id": "map", "kind": "mapper", "mapperId": "careers.example.jobs.fetchPayload" },
    { "id": "enqueue", "kind": "queue", "destinationId": "careers.fetch.queue" }
  ]
}

Las pipelines pueden escribirse directamente, partir de una plantilla o generarse con reglas sobre descriptores. Las variantes generadas enlazan los valores de forma explícita, por ejemplo "extractorId": "$extractor.id". Guida no adivina empresa, destino o contrato a partir de un ID, una ruta o un nombre de archivo.

Camino seguro hasta la ejecución

1. Draft y diff resuelven la definición efectiva y muestran los cambios propuestos.
2. Validate comprueba estructura, referencias, contratos y grafo.
3. Preflight revisa el espacio de trabajo y los requisitos operativos actuales.
4. Plan detalla etapas, conexiones, cambios previstos, capacidades, reglas, credenciales, procedencia, recuperación, bloqueos y avisos.
5. Preview devuelve un hash de la propuesta exacta e indica si está lista.
6. Start acepta entradas y límites de cola explícitos.

Guardar, eliminar y ejecutar son acciones distintas. Abrir o guardar un borrador nunca inicia una ejecución de forma implícita.

La ejecución crea una relación explícita con una ejecución del flujo de trabajo. El destino de cola declara si debe crear una ejecución aislada o usar una existente. Guida registra el estado de las etapas, dependencias, referencias de salida, deduplicación y resultados operativos.

workspace.pipelines.execution.lifecycle.get devuelve los estados gestionados por la pipeline. La vista previa, el inicio y el control del trabajo posterior son llamadas separadas. Los resultados de cola y registro se concilian de forma explícita: una cola vacía no demuestra por sí sola que la ejecución terminara bien.

La Remote Ops API ofrece contratos para lectura, borrador, diferencias, validación, preflight, plan, vista previa, ejecución, resultados, pruebas y control posterior. Guida Control utiliza estos contratos sin iniciar una pipeline al guardar un borrador.