Pipelines semânticas

Pipelines semânticas descrevem como dados regidos por contrato percorrem o Guida. Elas conectam uma origem ou um extrator a validadores, mapeadores e destinos e tornam a proposta de trabalho verificável antes da execução.

Uma pipeline não é uma pasta de fluxo de trabalho, um conjunto de processos de trabalho ou um agendador autônomo. Fluxos ativam o escopo operacional, processos consomem filas e o registro de rastreabilidade preserva os dados duráveis de execuções e itens. A pipeline une esses espaços com procedência explícita.

Modelo de etapas

Etapa	Responsabilidade
Source	Declara o tipo ou esquema de entrada
Extractor	Executa o contrato de um extrator identificado
Validator	Aplica um esquema e regras limitadas por item
Mapper	Transforma um contrato declarado em outro
Destination	Identifica uma fila ou outro destino compatível

Validadores, mapeadores e destinos formam catálogos reutilizáveis. Assim, regras e formatos de dados não ficam escondidos em scripts isolados.

{
  "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" }
  ]
}

Uma pipeline pode ser escrita diretamente, partir de um modelo ou ser gerada por regras sobre descritores. As variantes geradas vinculam valores de forma explícita, por exemplo "extractorId": "$extractor.id". O Guida não adivinha empresa, destino ou contrato com base em ID, caminho ou nome de arquivo.

Caminho seguro até a execução

1. Draft e diff resolvem a definição efetiva e mostram as alterações propostas.
2. Validate verifica estrutura, referências, contratos e grafo.
3. Preflight confere o espaço de trabalho e os requisitos operacionais atuais.
4. Plan mostra etapas, ligações, alterações previstas, capacidades, regras, credenciais, procedência, recuperação, bloqueios e avisos.
5. Preview devolve um hash da proposta exata e informa se ela está pronta.
6. Start recebe entradas e limites de fila explícitos.

Salvar, excluir e executar são operações separadas. Abrir ou salvar um rascunho nunca inicia uma execução implicitamente.

A execução cria uma relação explícita com uma execução do fluxo de trabalho. O destino da fila declara se deve criar uma execução isolada ou usar uma existente. O Guida registra estado das etapas, dependências, referências de saída, deduplicação e resultados operacionais.

workspace.pipelines.execution.lifecycle.get devolve os estados administrados pela pipeline. A visualização, o início e o controle do trabalho posterior são chamadas separadas. Resultados da fila e do registro são reconciliados explicitamente: uma fila vazia não comprova sozinha o sucesso da execução.

A Remote Ops API oferece contratos para leitura, rascunho, diferenças, validação, preflight, plano, visualização, execução, resultados, evidências e controle posterior. Guida Control usa esses contratos sem iniciar uma pipeline ao salvar um rascunho.